BNFS allows to create a CUBE SQLite network by importing links and nodes from:

• ESRI Shape Files (*.SHP).
• CUBE 6 Binary Networks (*.NET).
• SQLite databases (*.SQLite) layers.

This paragraph provides some examples of using this functionality.

Assuming to start with an ESRI Shape File for links and nodes, we can define two variables storing these inputs, as below (where data_dir is a variable that stores the input directory path, relative path for simplicity in the example, and the statement uses of a Python f-string).

data_dir = " input/shape_files/directory "
input_links = f"{data_dir}/Netowrk_Links.shp"
input_nodes = f"{data_dir}/Network_Nodes.shp"

First of all, we create a BNFSConfig object, and we store this in a variable, for the new network. BNFSConfig will provide the configuration for the BNFS process in terms of the new network name and various settings.

new_network_name = "Highway"
config = cp.BNFSConfig(new_network_name)

We should then setup the linkDatasource and nodeDataSource. Links are required whilst nodes are optional. In case a nodeDataSource is not specified, then nodes are created from inspecting the links.

In the example below, both the link and node data sources are supplied.

config.setLinkDataSource(input_links + "| SELECT * FROM Network_Links")  
config.setNodeDataSource(input_nodes + "| SELECT * FROM Network_Nodes")

Within these methods, CubePy GIS style path can be used that allows to supply a query on links and nodes, for the conversion. Queries are specified using the OGR SQL dialect. The query in the example above states to build the network for all the links and nodes ( SELECT *). In the example below instead, this statement will only build the network for those links satisfying the condition for column func_class to be equal 10.

config.setLinkDataSource(input_links + "| SELECT * FROM Network_Links where func_class=10")

The setMaxZoneNumber method allows to specify the maximum number of zones that are used in the input layer, so that BNFS will identify centroid nodes and centroid connectors. An example is given below, where the network has 25 zones in total.

config.setMaxZoneNumber(25)

The setStartingNodeNumber method instead, allows to specify what is the starting node number in case new node numbers are created while building the network, i.e., the link table does not contain A and B columns, and the node table does not contain N column. In the example below, the starting node number will be 1000. This parameter not only defines the initial node number when numbering the nodes though, it also defines two internal attributes of the network, i.e. minNodeNumber and maxNodeNumber, that are the minimum and maximum node numbers when excluding centroids. Therefore, in case the network already contains A and B nodes, it is necessary to set this parameter correctly (e.g., max zone number + 1). The default value is 10000.

config.setStartingNodeNumber(1000)

It is also possible to define the type of directionality for the links in the input link shape file. The BNFSLinkDirectionType assumes the following values:

To run an instance of BNFS with the defined configuration, it is necessary to connect to an existing or new CUBE database and call the BNFS method, like in the example below.

db = cp.CubeDatabase(output_db, True)  # "True" creates/re-creates the db
db.buildNetworkFromShape(config)

data_dir = "input/shape_files/directory"
input_net = f"{data_dir}/Netowrk.NET"

config.setLinkDataSource(input_net + f"| SELECT * FROM Link")
config.setNodeDataSource(input_net + f"| SELECT * FROM Node")

Note on setInputSpatialReferenceOverride

When using the BNFS tool, it is important to know the correct spatial reference of the links (and nodes) that are being imported for the correctness of the built network.

The setInputSpatialReferenceOverride method allows to define the authority code defining the spatial reference of the input data, according to spatialreference.org codes.

In case this is not explicitly specified by the user within this method, BNFS class uses the OGR library to fetch the spatial reference of the imported layers, in case the spatial reference is recognized (e.g., in the .PRJ file associated to the Shape File in input), then:

• If the layer stores the information about the authority code associated to the spatial reference (Spatial Reference ID), then:
  • If the authority code matches an authority code included in the EPSG catalog, this is adopted as spatial reference for the output network and BNFS is executed successfully.
  • If the authority code does not match any code included in the EPSG catalog, then an error message is issued, and the user needs to set the spatial reference override code manually and run the BNFS again.
• If the layer that is imported does not store the information about the authority code, then the OGR library will try to find a match within the EPSG catalog accordingly to search criteria that are based on the specification of the spatial reference for the layer (e.g., information stored in the PRJ file associated to the Shape File). Then:
  • If matches are found in the EPSG catalog, the best match is used by BNFS for building the CUBE network. The user should be aware that the match might not exactly correspond to the actual ID, in case of poor correspondence, therefore it might be necessary in some cases to enter the spatial reference override ID and re-run the BNFS also in this case.
  • If a match cannot be found in the EPSG catalog, then an error message is again returned, and the code must be inserted manually by the user to successfully run BNFS.

It is important to highlight that the EPSG catalog contains EPSG and ESRI references, but not other custom references. Therefore, in case of a custom reference for the input dataset, it is necessary to specify this within the setInputSpatialReferenceOverride method.

The SpatiaLite library table used by BNFS is updated to support EPSG, ESRI and custom references.

It is necessary to provide the Spatial Reference ID within the setInputSpatialReferenceOverride when using BNFS with CUBE 6 binary networks (.NET), due to the fact that they do not store spatial information.

In the example below, the setInputSpatialReferenceOverride is set to a custom spatial reference code 6826, corresponding to Clay county coordinates (feet).

config.setInputSpatialReferenceOverride(6826)